Report Playback & Engagement Events
Accurate event reporting is mandatory. It is how Feed ensures rights holders are paid correctly for the use of their music, and how your engagement metrics are calculated in Clips Studio. See The Rights & Licensing Model for why compliance matters.
Every event request must include a clientId and a timestamp.
For events that occur while a device is offline, see Handle Offline Playback.
In v1, all events were flat POST endpoints (e.g. /play, /add, /share). In v2, events are path-param endpoints scoped to the resource (e.g. POST /v2/clips/{id}/play, POST /v2/clips/{id}/share). The app start and close events follow the same pattern (ex: from /app-start to POST /v2/app/start).
App Open
Fire this event when the user opens your application.
Call the App Start endpoint (POST /v2/app/start). Include the user's clientId, the event timestamp, and the platform value for the device (e.g. ios, android, web).
In v1 this was POST /app-start.
App Close
Fire this event when the user closes your application.
Call the App Close endpoint (POST /v2/app/close). Include clientId and timestamp. The endpoint returns no content (204).
Play
Fire this event when a clip begins playback — including plays of UGC that contains a clip.
Call the Report Clip Play endpoint (POST /v2/clips/{id}/play), where {id} is the clip ID. Include clientId, timestamp, the playback method (Stream, Offline, or Sync), and whether the play is offline.
This endpoint also performs a final rights check. If the clip has lost rights since the last check, the response will indicate success: false with a failure code. Stop playback immediately in that case. In v1 this was POST /play.
Looping clip playback requires direct approval from rights holders for your use case. If content automatically loops playback without explicit user interaction, each subsequent clip play must trigger its own request to the play endpoint.
Preview
Fire this event when a user previews a clip (e.g. a short sample before confirming selection).
Call the Report Clip Preview endpoint (POST /v2/clips/{id}/preview), where {id} is the clip ID. Include clientId and timestamp.
In v1, previews were reported via POST /play with the preview: true parameter. In v2, preview is a dedicated endpoint.
Track Play
Fire this event when a user begins playing a full-length track — typically during the custom clip creation flow while auditioning sections of the track.
Call the Report Track Play endpoint (POST /v2/tracks/{id}/play), where {id} is the track ID. Include clientId and timestamp. The endpoint returns no content (204).
Add to Content
Fire this event when the user confirms selection of a clip for their content.
Call the Add Clip to Content endpoint (POST /v2/clips/{id}/add), where {id} is the clip ID. Include clientId, timestamp, and the playback method (Stream, Offline, or Sync). The endpoint returns no content (204). In v1 this was POST /add.
Share
Fire this event when a user shares content containing a clip to an approved third-party platform (for example, social media).
Call the Share Clip endpoint (POST /v2/clips/{id}/share), where {id} is the clip ID. Include clientId, timestamp, the platform (e.g. instagram), and the shareUri identifying the shared content. The endpoint returns no content (204).
Download
Fire this event when a user downloads content containing a clip to their device.
Call the Download Clip endpoint (POST /v2/clips/{id}/download), where {id} is the clip ID. Include clientId and timestamp. The endpoint returns no content (204).
Allowing users to download content containing a Feed Clip requires direct approval from rights holders specific to your product's use case. Contact us if you're interested in this capability so we can arrange for approval.